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Production Note 


This book was produced with the VAX DOCUMENT electronic publishing 
system, a software tool developed and sold by DIGITAL. In this system, 
writers use an ASCII text editor to create source files containing text and 
English-like code; this code labels the structural elements of the document, 
such as chapters, paragraphs, and tables. The VAX DOCUMENT software, 
which runs on the VMS operating system, interprets the code to format the 
text, generate a table of contents and index, and paginate the entire document. 
Writers can print the document on the terminal or line printer, or they can use 
DIGITAL-supported devices, such as the LN03 laser printer and PostScript 
printers (PrintServer 40 or LN03R ScriptPrinter), to produce a typeset-quality 
copy containing integrated graphics. 


/ 




PostScript is a trademark of Adobe Systems, Inc. 
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Preface 


This manual provides users of the VMS operating system with detailed usage 
and reference information on DECtalk support routines supplied in the DTK$ 
facility of the Run-Time Library. 

Run-Time Library routines can only be used in programs written in languages 
that produce native code for the VAX hardware. At present, these languages 
include VAX MACRO and the following compiled high-level languages: 


VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 


Ada 

BASIC 

BLISS-32 

C 

COBOL 

COBOL-74 

CORAL 

DIBOL 

FORTRAN 

Pascal 

PL/I 

RPG 

SCAN 


Interpreted languages which can also access Run-Time Library routines 
include VAX DSM and DATATRIEVE. 


Intended Audience 

This manual is intended for system and applications programmers who want 
to call Run-Time Library routines. 


Document Structure 

This manual is organized into two parts as follows: 







Chapter 1 provides guidelines on using the DTK$ DECtalk routines. 

The DTK$ Reference Section provides detailed reference information on 
each DECtalk support routine contained in the DTK$ facility of the Run¬ 
Time Library. This information is presented using the documentation 
format described in the Introduction to the VMS Run-Time Library. Routine 
descriptions appear in alphabetical order by routine name. 


vii 








Preface 


Associated Documents 

The Run-Time Library routines are documented in a series of reference 
manuals. This manual provides an overview of the VMS Run-Time Library 
DECtalk (DTK$) facility, along with detailed information on each DTK$ 
routine. A general overview of the VMS Run-Time Library is presented in 
the Introduction to the VMS Run-Time Library. Descriptions of the other RTL 
facilities and their corresponding routines and usages are discussed in the 
following books: 

• The VMS RTL Library (UBS) Manual 

• The VMS RTL Mathematics (MTH$) Manual 

• The VMS RTL General Purpose (OTS$) Manual 

• The VMS RTL Parallel Processing (PPL$) Manual 

• The VMS RTL Screen Management (SMG$) Manual 

• The VMS RTL String Manipulation (STR$) Manual 

The VAX Procedure Calling and Condition Handling Standard, which is 
documented in the Introduction to System Routines, contains useful information 
for anyone who wants to call Run-Time Library routines. 

Applications programmers of any language may refer to the Guide to Creating 
VMS Modular Procedures for the Modular Programming Standard and other 
guidelines. 

High-level language programmers will find additional information about 
calling Run-Time Library routines in their language reference manual. 
Additional information may also be found in the language user's guide 
provided with your VAX language. 

The Guide to Using VMS Command Procedures may also be useful. 

For a complete list and description of the manuals in the VMS documentation 
set, see the Overview of VMS Documentation. 
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Preface 


Conventions 


Convention 

Meaning 

|ret| 

In examples, a key name (usually abbreviated) 
shown within a box indicates that you press 
a key on the keyboard; in text, a key name is 
not enclosed in a box. In this example, the key 
is the RETURN key. (Note that the RETURN 
key is not usually shown in syntax statements 
or in all examples; however, assume that you 
must press the RETURN key after entering a 
command or responding to a prompt.) 

CTRL/C 

A key combination, shown in uppercase with a 
slash separating two key names, indicates that 
you hold down the first key while you press the 
second key. For example, the key combination 
CTRL/C indicates that you hold down the key 
labeled CTRL while you press the key labeled C. 
In examples, a key combination is enclosed in a 
box. 

$ SHOW TIME 

05-JUN-1988 11:55:22 

In examples, system output (what the system 
displays) is shown in black. User input (what 
you enter) is shown in red. 

$ TYPE MYFILE.DAT 

In examples, a vertical series of periods, or 
ellipsis, means either that not all the data that 
the system would display in response to a 
command is shown or that not all the data a 
user would enter is shown. 

input-file, . . . 

In examples, a horizontal ellipsis indicates 
that additional parameters, values, or other 
information can be entered, that preceding 
items can be repeated one or more times, or 
that optional arguments in a statement have 
been omitted. 

[logical-name] 

Brackets indicate that the enclosed item is 
optional. (Brackets are not, however, optional 
in the syntax of a directory name in a file 
specification or in the syntax of a substring 
specification in an assignment statement.) 

quotation marks 
apostrophes 

The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe (') is used to refer to a single 
quotation mark. 


Other conventions used in the documentation of Run-Time Library routines 
are described in the Introduction to the VMS Run-Time Library. 
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DECtalk Guidelines 


This section discusses the Run-Time Library routines that control and perform 
various functions on DIGITAL's DECtalk device. The DECtalk routines are 
meant solely for use with DIGITAL's DECtalk device. 


1.1 Overview of the DTK$ Facility 

The DECtalk device accepts alphanumeric text from a computer system and 
converts it to human-quality speech. DECtalk speaks this data through its 
internal speaker, an external audio system, or over the telephone. 

The DTK$ Facility consists of routines that control the functions of the 
DECtalk device. These routines not only control DECtalk's characteristics, but 
they also provide functional controls such as reading keys entered on a phone 
keypad or hanging up the phone. In general, the DTK$ routines supply a 
simple interface between the user and the DECtalk device. 


1.2 Controlling the DECtalk Environment 

The DTK$ facility supplies several routines that control the environment in 
which the DECtalk device functions. These routines are grouped according to 
function and described in the following subsections. 


1.2.1 Initializing DECtalk 

Before issuing any commands to the DECtalk device, you must first initialize 
it. The routine DTK$INITIALIZE initializes a DECtalk device and returns 
its associated voice identifier. This routine also specifies a file specification 
or logical name to which the output associated with the DECtalk device is 
written. 


1.2.2 The DECtalk Device 

Once a DECtalk device has been initialized, you can select various operating 
modes for the device. One of these modes involves the specification of 
phonemic text; a phoneme is one of the smallest possible units of speech that 
can be used to distinguish one word from another. 

DTK$SET_MODE enables you to select any operating mode for DECtalk. The 
DTK$SET_MODE routine controls how DECtalk processes text, according to 
the modes in the following list. Note that it is possible to perform a logical 
OR operation to set more than one mode at a time, and any mode that is not 
specified is reset. 

• DTK$M_SQUARE treats square brackets ([ ]) as phonemic text delimiters. 
The DTK$M-SQUARE mode also lets the close parenthesis character 
when it appears before a word, indicate an alternative pronunciation from 
the built-in dictionary. 
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• DTK$M—ASCII uses single-character phonemic translation instead of a 
multiletter translation. This is valid only for the DTC01 device. 

• DTK$M_MINUS pronounces a hyphen (-) as "minus." 

• DTK$M_EUROPE uses European number format (where a comma 
separates the number from its decimal portion and periods mark off digits 
into groups of 3). This is valid only for the DTC03 device. 

• DTK$M—SPELL spells out all text instead of interpreting the text as 
words. This is valid only for the DTC03 device. 

DTK$SET_MODE can be used to set new modes, to examine the current 
mode settings, or to change the modes and later return them to their previous 
state. 

The DTK$SET_SPEECH_MODE routine toggles DECtalk's speech on and off. 
In the case of turning the speech off, you can either cause DECtalk to stop 
speaking immediately or to stop speaking when the current text is completed. 

DTK$SET_VOICE controls the actual voice characteristics of the DECtalk 
device. The following is a list of the available voice mode settings for 
DECtalk, along with their characteristics. 


Voice Mode 

Characteristics 

DTK$K_VOICE_MALE 

Standard male voice 

DTK$K_VOICE_FEMALE 

Standard female voice 

DTK$K_VOICE_CHILD 

Standard child voice 

DTK$K_VOICE_DEEP_MALE 

Deep male voice 

DTK$K_VOICE_DEEP_FEMALE 

Deep female voice 

DTK$K_VOICE_OLDEFt_MALE 

Older male voice 

DTK$K_VOICE_LIGHT_FEMALE 

Light female voice 


The DTK$SET_VOICE routine also enables you to control DECtalk's speech 
rate, as well as the length of the pauses after commas and periods. The 
speech rate of the DECtalk device is measured in words per minute, and 
the valid range is 120 to 350 words per minute. The values that control the 
comma and period pauses are measured in milliseconds. 


1.2.3 The Terminal 


The DECtalk device enables you to connect a local terminal to the DECtalk 
device. The DTK$ facility supplies two routines that you can use to control 
the local terminal. 

The DTK$SET_LOGGING_MODE routine determines the information that 
is displayed on the local terminal connected to the DECtalk device. The 
following is a list of modes that can be set or reset using 
DTK$SET_LOGGING_MODE. Note that you can perform a logical OR 
operation to set more than one mode at a time, and any mode not specified is 
reset. 

• DTK$M_TEXT causes all spoken text to be printed on the terminal. 
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• DTK$M_PHONEME causes all spoken text to be converted to its 
phonemic equivalent and then printed on the terminal. 

• DTK$M _RAWHOST causes all data received from the host to be 
transmitted, including escape sequences, to the terminal in exactly the 
form in which it is received. 

• DTK$M-INHOST causes all text received from the host to be printed, 
including escape sequences, on the terminal. However, all control 
characters are first translated to a readable form. 

• DTK$M_OUTHOST causes all characters sent to the host to be printed 
at the terminal. Before printing, control characters are converted to 

a readable form. This readable form is sometimes a mnemonic (for 
example, ESC for escape) and sometimes a letter that has meaning when 
used with the CTRL key (for example, C for CTRL/C). 

• DTK$M-ERROR causes all DECtalk error messages to be printed on the 
terminal. 

• DTK$M-TRACE causes all text received from the host to be printed on 
the terminal, including escape sequences. However, the escape sequences 
are first converted into their symbolic meaning before being printed. 

The routine DTK$SET_TERMINAL _MODE controls the attributes of the 
local terminal. This routine can be used to set new modes, to examine the 
current mode settings, or to change the modes and later return them to their 
previous state. All of the following modes are valid. 


DTK$M_HOST 

When set, any characters typed on the local terminal are 
transmitted to the host computer. 

DTK$M_SPEAK 

When set, characters typed on the local terminal are 
spoken by DECtalk. (Note that they will be interspersed 
with characters sent from the host.) 

DTK$M_EDITED 

When set, text entered from the local terminal is processed 
one line at a time. 

DTK$M_HARD 

When set, text is echoed on the local terminal in a manner 
appropriate for hardcopy terminals. When this mode is not 
set, echoing is performed in a manner appropriate for video 
display terminals. 

DTK$M -SETUP 

When set, DECtalk speaks the set-up dialogue. 

DTK$M_FILTER 

When set, DECtalk does not transmit DECtalk-specific 
escape sequences to the local terminal. DECtalk also 
ignores most non-DECtalk escape sequences transmitted 
from the host computer. 


Once again, it is possible to perform a logical OR operation to set more than 
one mode at a time. Any mode that is not specified is automatically reset. 
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1.2 Controlling the DECtalk Environment 


1.2.4 The Index 


When DECtalk speaks text, the speech rate for the device is much slower 
than the rate of data transmission. This may create a problem if a certain 
task in your program is contingent upon certain speech being complete. For 
example, it is quite likely that the DECtalk device will still be speaking some 
text while your program is already executing the next statement. The DTK$ 
facility therefore provides you with indexes. An index is a number that you 
insert at an appropriate location in your text. Once DECtalk finishes speaking 
all text up to that index, the index value is returned to your program. Using 
this index, your program can then keep track of text that has already been 
spoken. 

An index could be inserted, for example, following some instructional text 
regarding user input. Once DECtalk speaks the instructional text, it returns 
the index to the program, and this triggers the program to wait for the user's 
input. You can set an index using the DTK$SET_INDEX routine. The index 
value must be in the range of 1 to 32767. The DTK$RETURN_LAST_INDEX 
routine returns the last index spoken. 


1.2.5 The Dictionary 

DECtalk comes equipped with two dictionaries. The first of these is stored 
in ROM and therefore cannot be changed in any way. A certain amount of 
dynamic storage is allocated for a supplemental dictionary to which you can 
add your own words and pronunciations. 

To load a word into this supplemental dictionary, you use the 
DTK$LOAD_DICTIONARY routine. By specifying both the actual spelling 
of the word and its phonemic definition, you create a new entry in the 
supplemental dictionary. 


1.2.6 Terminating DECtalk 

To deassign the voice identifier that was assigned to the DECtalk device when 
it was initialized, you must call DTK$TERMINATE. This routine terminates 
all use of the specified DECtalk device by deallocating the voice control block 
and all of its substructures. 


1.3 Controlling DECtalk's Speech 

The DTK$ facility provides three different methods for specifying the text that 

DECtalk is to speak. 

DTK$SPEAK_TEXT sends the specified text to the DECtalk device to be 

spoken. You can optionally set one of the following modes: 

• DTK$K_IMMED returns control to the user immediately (this is the 
default). 

• DTK$K_WAIT waits until the text is completely spoken before returning 
control to the user. 

• DTK$K_STATUS waits until the text is completely spoken, and then 
returns a phone status. 
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1.3 Controlling DECtalk's Speech 


These modes can be set for DTK$SPEAK —FILE, which speaks the text 
contained in a specified file, and also for DTK$SPEAK_PHONEMIC_TEXT. 
This routine sends the specified phonemic text to the DECtalk device to be 
spoken. Phonemic text contains the phonemic representations of the words 
to be spoken; that is, the words are spelled as they are pronounced. 


1.4 Controlling DECtalk for Telephone Use 

One of the most common applications for DECtalk is to serve as an access 
to a remote database via the telephone. The DTK$ facility therefore supplies 
several routines that improve the interface between DECtalk and the user. 


1.4.1 The Telephone Keypad 

The routine DTK$SET_KEYPAD_MODE enables and disables DECtalk's 
recognition of the telephone keypad. If keypad recognition is enabled with 
autostop, DECtalk stops speaking when a terminator is entered. Otherwise, 
keypad recognition is disabled immediately. 


1.4.2 Input Using the Telephone Keypad 

The routine DTK$READ_KEYSTROKE reads a key entered on the telephone 
keypad and returns that key's equivalent key code value. These key codes 
are in the form DTK$K_TRM_rcxx, and they are defined in the DIGITAL 
supplied library $DTKDEF. The optional prompt argument enables you to 
specify some text that DECtalk speaks before waiting for input. The timeout 
argument controls the number of seconds that DECtalk waits for input. 

DTK$READ_STRING reads a series of keys entered on a telephone keypad 
and returns the key series as a single string. Again, you can specify 
an optional prompt and a timeout value for this routine. The optional 
termination code argument returns the key code value of the terminating key 
entered. 


1.4.3 Controlling the Telephone Functions 

In addition to accepting user input, the DTK$ facility also supplies routines 
that control the actual operation of the telephone. 

DTK$ANSWER_PHONE waits for the phone connected to the DECtalk 
device to ring and then answers it. You can specify optional text that DECtalk 
speaks after answering the phone. The DTK$ facility also supplies a routine 
for hanging up the phone; DTK$HANGUP_PHONE. This routine speaks an 
optional message (if specified) and then hangs up the phone. 

DTK$DIAL—PHONE dials the specified number on the telephone. You can 
select either pulse dialing or tone dialing with the mode argument for this 
routine, and you can specify how many seconds DECtalk should wait for the 
phone to be answered. The text argument enables you to specify optional text 
that DECtalk speaks after the phone is answered. 
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1.5 Exit Handlers 



1.5 Exit Handlers 

The DTK$ facility supplies its own exit handler to terminate access to the 
DECtalk device. This exit handler hangs up the phone and resets any 
terminal characteristics changed by the DTK$ facility. Users must not call 
any of the DTK$ routines from within their own exit handlers. 
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DTK$ Reference Section 


This section provides detailed discussions of the routines provided by the 
VMS RTL DECtalk (DTK$) Facility. 










DTK$ANSWER_PHONE 


DTK$ANSWER_PHONE Wait for Phone to Ring 

and Answer 



The Wait for Phone to Ring and Answer routine waits for the phone 
connected to the DECtalk device to ring and then answers it. 

FORMAT 

DTK$ANSWER_PHONE voice-id [,number-of-rings] 

[,text] [,timeout] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

number-of-rings 

VMS usage: longword_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Number of rings DECtalk waits for before answering the phone. The optional 
number-of-rings argument is the address of a signed longword containing 
this number. The default is 1 ring. 

text 

VMS usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text that DECtalk speaks after answering the phone. The optional text 
argument is the address of a descriptor pointing to the text. 

timeout 

VMS usage: longword_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 
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DTK$ANSWER_PHONE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


Number of seconds that DECtalk allows the phone to ring before answering. 
The optional timeout argument is the address of a signed longword 
containing this timeout value. There is no default value. 


DTK$ANSWER _PHONE waits for the phone connected to the DECtalk 
device to ring and then answers it. If the number-of-rings argument is not 
specified, DECtalk answers the phone after 1 ring. If both the number-of- 
rings argument and the timeout argument are specified, DECtalk answers the 
phone after the first argument occurs. For example, if you specify 2 rings and 
30 seconds, DECtalk will answer after 2 rings. After the phone is answered, 
DECtalk speaks any optional text that you specified. 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 


Normal successful completion. 

Any condition value returned by $QIOW. 
Invalid voice-id. 

Wrong number of arguments. 
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DTK$C H EC K _H D WR —STATUS 


DTK$CHECK_HDWR_STATUS Check Hardware 

Status 



The Check Hardware Status routine checks the DECtalk hardware for 
hardware malfunctions. 

FORMAT 

DTK$CHECK_HDWR—STATUS voice-id ,hdwr-status 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

hdwr-status 

VMS usage: mask_longword 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Receives the hardware status of the DECtalk machine. The hdwr-status 
argument is the address of an unsigned longword bit mask that receives the 
status. 

Valid values for hdwr-status are: 

DTK$_NOMALFUN1 No malfunctions on first test 

DTK$_NOMALFUN2 No malfunctions on second test 

DTK$_COMFAIL Communication failure 

DTK$_INPBUFOVR Input buffer overflow 

DTK$_NVROPRFAI NVR operation failed 

DTK$_ERRPHOTRA Phonemic transmission error 

DTK$_CONSEQERR Control sequence error 

DTK$_DECTSFAI Self-test failed 
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DTK$CHECK_HDWR_STATUS 



DESCRIPTION The DTK$CHECK_HDWR_STATUS routine checks the DECtalk hardware 


(described by the voice-id argument) for hardware malfunctions and returns 
the status to the caller. 

If more than one hardware malfunction occurs, you can invoke the 
DTK$CHECK_HDWR_STATUS routine as many times as necessary to 
retrieve all error status codes. A status of "no malfunctions" indicates that 
there are no further error status codes to be retrieved. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

LIB$_xxxx 


Normal successful completion. 

Any error from $QIOW. 

Invalid voice-id. 

Wrong number of arguments. 

Any error from LIB$GET_VM or LIB$FREE_VM. 
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DTK$DIAI_PHONE 


DTK$DIAL. 

_PHONE Dial the Telephone 

The Dial the Telephone routine dials the specified number on the 
telephone. 

FORMAT 

DTK$DIAI_PHONE voice-id ,phone-number 

[, dial-mode] [, text] [, timeout] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk machine. The voice-id argument is the 
address of an unsigned longword containing this identifier. The voice 
identifier is returned by the DTK$INITIALIZE routine. 

phone-number 

VMS usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Phone number to dial. The phone-number argument is the address of a 
descriptor pointing to the specified phone number. 

dial-mode 

VMS usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mode to use when dialing the phone. The optional dial-mode argument is 
the address of an unsigned longword containing this mode. 

The valid modes are: 

DTK$K_DIAI PULSE Use pulse dialing. 

DTK$K_DIAI TONE Use tone dialing. 

Pulse dialing is the default. Tone dialing requires a touch tone telephone; 
there are, however, touch tone phones that have a pulse dialing mode. 
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DTK$DIAI_PHONE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


text 

VMS usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Text to be spoken after the phone is answered. The text argument is the 
address of a descriptor pointing to the specified text. 


timeout 

VMS usage: 
type: 
access: 
mechanism: 


longword_signed 
longword (signed) 
read only 
by reference 


Number of seconds to wait for the phone to be answered. The optional 
timeout argument is the address of a signed longword containing this timeout 
value. If omitted, DECtalk dials the phone and immediately returns control 
to the calling program. 


DTK$DIAL —PHONE dials the specified number on the telephone. If a call is 
currently active, DECtalk does not hang up the phone. 

Note that this routine does not ensure that the phone is answered; it simply 
dials the specified telephone number. If the user specifies the optional text 
argument, DECtalk speaks this text before returning control to the calling 
program. 

If the timeout argument is specified, the DTC01 device always waits for the 
specified number of seconds before returning control, even if the phone is 
answered before the specified number of seconds has elapsed. On the other 
hand, the DTC03 device interprets the timeout argument as the maximum 
number of seconds to wait before returning control to the calling program. 
That is, the DTC03 device returns control either when the phone is answered 
or when the timeout argument has expired, whichever occurs first. 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_T OOLONG 

DTK$_INVMODE 

DTK$_OFFHOOK 


Normal successful completion. 

Any error from $QIOW. 

Invalid voice-id. 

Wrong number of arguments. 

Phone number is too long. 

Invalid mode specified. 

Phone is off hook (phone is already active). 
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DTK$HANGUP_PHONE 


DTK$HANGUP_PHONE Hang Up the Phone 



The Hang Up the Phone routine speaks an optional message and then 
hangs up the phone. 

FORMAT 

DTK$HANGUP_PHONE voice-id [, text] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

text 

VMS usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text to be spoken before hanging up the phone. The optional text argument 
is the address of a descriptor pointing to the specified text. 

DESCRIPTION 

DTK$HANGUP—PHONE hangs up the phone after speaking an optional 
message. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SS$_xxxx Any error from $QIOW. 

DTK$_INVVOIID Invalid voice-id. 

DTK$_WRONUMARG Wrong number of arguments. 
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DTK$INITIALIZE 


DTK$INITIALIZE Initialize DECtalk 



The Initialize DECtalk routine initializes a DECtalk device and returns the 
device's assigned voice identifier. 

FORMAT 

DTK$INITIALIZE voice-id , output-device [,device-type] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Voice identifier of the newly created DECtalk device. The voice-id argument 
is the address of an unsigned longword that receives this identifier. 

output-device 

VMS usage: device—name 
type: character string 

access: read only 

mechanism: by descriptor 

File specification or logical name to which the output associated with the 
DECtalk device is written. The output-device argument is the address of a 
descriptor pointing to this logical name. 

device-type 

VMS usage: longword_signed 
type: longword (signed) 

access: write only 

mechanism: by reference 

Device type of the newly created DECtalk device. The optional device-type 
argument is the address of a signed longword that receives the device-type 
information. The two valid device types are: 

DTK$K_DTC_01 For DECtalk 1. 

DTK$K_DTC_03 For DECtalk III. 

If the device-type information is not received in time, the assigned device¬ 
type is DTK$K_DTC—UNKNOWN. 
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DTK$INITIALIZE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


DTK$INITIALIZE creates a DECtalk device and returns its assigned voice 

identifier, voice-id. Output-device is the device to which the output 
associated with this newly created DECtalk is written. 

If DTK$INITIALIZE is called to create a second DECtalk on a device that 
already has a voice identifier associated with it, DTK$INITIALIZE simply 
returns the identifier of the already existing DECtalk, along with the condition 
code DTK$_VOIALREXI, which signifies that DECtalk already exists for this 
device. 


SS$_NORMAL 

SS$_xxxx 

RMS$_xxxx 

LIB$_xxxx 

LIBS—INSVIRMEM 

DTKS—VOIALREXI 

DTK$_WRONUMARG 


Normal successful completion. 

Any error from $GETDVI. 

Any error from SPARSE. 

Any error from LIB$GET_VM or LIB$GET_EF. 
Insufficient virtual memory to allocate needed 
buffer. 

DECtalk already exists for this device. 

Wrong number of arguments. 
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DTK$LOAD_DICTIONARY 


4 


DTK$LOAD_DICTIONARY Load a Word into the 



DECtalk Dictionary 

The Load a Word into the DECtalk Dictionary routine loads a phonemic 
definition of a word into the DECtalk dictionary. 

FORMAT 

DTK$LOAD_DICTIONARY voice-id, text .substitution 

RETURNS 

VMS usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

text 

VMS usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Word to be loaded into the DECtalk dictionary. The text argument is the 
address of a descriptor pointing to the specified word. 

substitution 

VMS usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Phonemic definition of the word specified by the text argument. The 
substitution argument is the address of a descriptor pointing to the phonemic 
representation of the specified word. 

DESCRIPTION 

DTK$LOAD_DICTIONARY loads the phonemic definition of a specified 
word into the DECtalk dictionary. 
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DTK$LOAD_DICTIONARY 


CONDITION 

VALUES 

RETURNED 


SS$—NORMAL 
DTK$_WRONUMARG 
DTK$_INVVOIID 
DTK$_NOROOM 

DTK$_DEFT OOLONG 


Normal successful completion. 

Wrong number of arguments. 

Invalid voice-id. 

No room in the dictionary to add the specified 
word. 

Word definition is too long. 
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DTK$READ_KEYSTROKE 


DTK$READ_KEYSTROKE Read a Key Entered on 

the Keypad 

The Read a Key Entered on the Keypad routine reads a key entered on the 
phone keypad. 


FORMAT 

DTK$READ_KEYSTROKE 

voice-id ,key-code 
[,prompt-string] [, timeout] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 



Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


key-code 

VMS usage: 
type: 
access: 
mechanism: 


longword_signed 
longword (signed) 
write only 
by reference 


The DTK$K_TRM_xxxx code for the key entered on the keypad. The key- 
code argument is the address of a signed longword that receives this code. 
The valid codes are listed in DTKDEF. 


prompt-string 


VMS usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Text to be spoken before waiting for input. The optional prompt-string 
argument is the address of a descriptor pointing to this text. 


timeout 

VMS usage: 
type: 
access: 
mechanism: 


longword_signed 
longword (signed) 
read only 
by reference 
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DTK$READ_KEYSTROKE 



Number of seconds to wait for input. The optional timeout argument is the 
address of a signed longword containing the specified number of seconds 
the DECtalk device waits for input. If the timeout argument is omitted, 
DTK$READ_KEYSTROKE waits for input indefinitely. 

DESCRIPTION 

DTK$READ KEYSTROKE reads a key entered on the phone keypad. If the 

optional text argument is specified, DECtalk speaks this text before waiting 
for input. If the keypad mode has not yet been set, this routine will set the 
phone keypad to auto-stop mode. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SS$_xxxx Any error from $QIOW. 

DTK$_INVVOIID Invalid voice-id. 

DTK$_WRONUMARG Wrong number of arguments. 

DTK$_ONHOOK Phone is on the hook (inactive). 

DTK$_WINK A wink has occurred. 
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DTK$READ_STRING 


DTK$READ STRING Read a Series of Keys 

Entered on the Keypad 

The Read a Series of Keys Entered on the Keypad routine reads a series of 
keys entered on the phone keypad. 


FORMAT 


DTK$READ_STRING voice-id, resultant-string 

[, prompt-string] [, timeout] 
[Jongword-integer-termin-code] 


RETURNS 


VMS usage: 

type: 

access: 

mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS 


voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


resultant-string 


VMS usage: 
type: 
access: 
mechanism: 


char_string 
character string 
write only 
by descriptor 


String into which the keys being read are written. The resultant-string 
argument is the address of a descriptor pointing to this string. 


prompt-string 


VMS usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Text to be spoken before waiting for input. The optional prompt-string 
argument is the address of a descriptor pointing to this text. 


timeout 

VMS usage: 
type: 
access: 
mechanism: 


longword_signed 
longword (signed) 
read only 
by reference 
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DTK$READ_STRING 



Number of seconds DECtalk waits for input. The optional timeout argument 
is the address of a signed longword containing the number of seconds 
DECtalk waits for input. If the timeout argument is omitted, 
DTK$READ_STRING waits for input indefinitely. 

longword-integer-termin-code 

VMS usage: longword_signed 
type: longword (signed) 

access: write only 

mechanism: by reference 

The DTK$K_TRM_xxxx code for terminating key entered. The optional 
longword-integer-termin-code argument is the address of a signed longword 
that receives this code. The valid codes are located in DTKDEF. 

DESCRIPTION 

DTK$READ STRING reads a series of keys entered on the phone keypad 

and stores them in resultant-string. If the optional prompt-string argument 
is specified, DECtalk speaks the specified text before waiting for input. The 
valid terminators are the number sign (#) and the asterisk (*). If the keypad 
mode has not yet been set, this routine will set the phone keypad to auto-stop 
mode. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SS$_xxxx Any error from $QIOW. 

DTK$_INVVOIID Invalid voice-id. 

DTK$_WRONUMARG Wrong number of arguments. 

DTK$_ONHOOK Phone is on the hook (inactive). 

DTK$_WINK A wink has occurred. 
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DTK$RETURN_LAST_INDEX 


DTK$RETURN LAST INDEX Return Last Index 



Spoken 

The Return Last Index Spoken routine returns the last index spoken. 

FORMAT 

DTK$RETURN_LAST_INDEX voice-id ,p-index 

RETURNS 

VMS usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

p-index 

VMS usage: longword_signed 
type: longword (signed) 

access: write only 

mechanism: by reference 

Index to be returned. The p-index argument is the address of a signed 
longword that receives the index identifier. 

DESCRIPTION 

DTK$RETURN_LAST_INDEX returns the last index spoken. An index is 
inserted into the output stream with the DTK$SET_INDEX routine. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SS$_xxxx Any error from $QIOW. 

DTK$_INVVOIID Invalid voice-id. 

DTK$_WRONUMARG Wrong number of arguments. 
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DTK$SET_INDEX 


DTK$SET_INDEX Insert an Index at the Current 

Position 

The Insert an Index at the Current Position routine inserts an index into the 
current output stream. 


FORMAT DTK$SET_INDEX voice-id ,p-index 


RETURNS 


VMS usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS 


voice-id 

VMS usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


p-index 

VMS usage: 
type: 
access: 
mechanism: 


longword—signed 
longword (signed) 
read only 
by reference 


Index to be inserted. The p-index argument is the address of a signed 
longword containing the index value. Valid values are in the range of 1 to 
32767. An index of zero is reserved for use by DIGITAL. 


DESCRIPTION DTK$SET_INDEX inserts an index into the current position in the output 

stream. Allowable values for p-index are in the range of 1 to 32767. An 
index of zero is reserved for use by DIGITAL. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVARG 


Normal successful completion. 
Any error from $QIOW. 

Invalid voice-id. 

Wrong number of arguments. 
Invalid argument. 


DTK-19 













DTK$SET_KEYPAD_MODE 


DTK$SET KEYPAD MODE Turn the Phone 



Keypad On and Off 

The Turn the Phone Keypad On and Off routine turns recognition of the 
telephone keypad on or off. 

FORMAT 

DTK$SET_KEYPAD_MODE voice-id,keypad-mode 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

keypad-mode 

VMS usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mode that determines the status of the telephone keypad. The keypad-mode 
argument is the address of an unsigned longword containing this mode. The 
valid mode specifiers are: 

DTK$K_KEYPAD_ON Turns the keypad on. 

DTK$K_KEYPAD_OFF Turns the keypad off. 

DTK$K_KEYPAD_AUTO Turns the keypad on with autostop. 

DESCRIPTION 

DTK$SET_KEYPAD_MODE turns the recognition of the telephone keypad 
on or off. Depending upon the keypad-mode specified, the keypad can be 
turned on, off, or on with autostop. Autostop means that DECtalk stops 
speaking when a terminator is entered. 
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DTK$SET_KEYPAD_MODE 


Normal successful completion. 
Wrong number of arguments. 
Invalid voice-id. 

Phone is on the hook (inactive) 
Invalid mode specified. 

A wink has occurred. 






CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

DTK$_WRONUMARG 

DTK$_INVVOIID 

DTK$_ONHOOK 

DTK$_INVMODE 

DTKS—WINK 
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DTK$SET_LOGGING_MODE 


DTK$SET LOGGING MODE Set the Logging 

Mode for the Video 
Terminal Connected 
to the DECtalk 
Device 

The Set the Logging Mode for the Video Terminal Connected to the 
DECtalk Device routine controls the information that is displayed on the 
video terminal while the DECtalk device is functioning. 


FORMAT 

DTK$SET_LOGGING_MODE 

voice-id [, new-mode] 

[, old-mode] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 



Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


new-mode 

VMS usage: mask-long word 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

DECtalk mode to be set. The optional new-mode argument is the address 
of a longword bit mask containing the specified mode. Valid values for 
new-mode are: 

• DTK$M_TEXT 

• DTK$M_PHONEME 

• DTK$M_RAWHOST 

• DTK$M_INHOST 

• DTK$M_OUTHOST 

• DTK$M_ERROR 
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DTK$SET_LOGGING_MODE 


DESCRIPTION 


• DTK$M—TRACE 

• DTK$M —DEBUG 

It is possible to perform a logical OR operation on the bits in the bit mask 
together to set more than one mode at a time. Any mode not specified is 
reset. 


old-mode 


VMS usage: 
type: 
access: 
mechanism: 


mask—longword 
longword (unsigned) 
write only 
by reference 


Current mode settings of the DECtalk device. The optional old-mode 
argument is the address of a longword bit mask that receives the current 
DECtalk settings. 


DTK$SET_LOGGING —MODE sets or resets the specified modes on the 
DECtalk device. It controls the information that is displayed on a video 
terminal connected to the DECtalk device. Note that any modes not explicitly 
set are reset by DTK$SET_LOGGING—MODE. 

DTK$SET_LOGGING—MODE has two optional parameters, new-mode and 
old-mode. By specifying different combinations of these arguments, you can 
use DTK$SET_LOGGING —MODE in various ways. 

• To use DTK$SET_LOGGING-MODE to determine the current mode 
settings, use the following format: 

DTK$SET_LOGGING_MODE (voice_id „old_mode) 

• To use DTK$SET_LOGGING —MODE to set the bits without regard to 
their current setting, use the following format: 

DTK$SET_LOGGING_MODE (voice_id ,new_mode) 

• To use DTK$SET_LOGGING—MODE to save the current settings, set 
new modes, and later restore the original settings, use the following 
format: 

DTK$SET_LOGGING_MODE (voice_id ,new_mode ,save_old_settings) 

This retrieves the current bit settings and then sets the mode according to 
the new-mode argument. 

Later, to restore the mode to its former state, specify the following 
format: 

DTK$SET_LOGGING_MODE (voice-id ,save_old_settings) 

This sets the new mode settings according to those previously retrieved. 
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DTK$SET_LOGGING_MODE 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

DTK$_WRONUMARG 

DTK$_INVVOID 

DTK$_INVMODE 


Normal successful completion. 
Wrong number of arguments. 
Invalid voice-id. 

Invalid mode specified. 
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DTK$SET_MODE 


DTK$SET_MODE Set the Mode for the DECtalk 

Terminal 


The Set the Mode for the DECtalk Terminal routine sets or resets the 
mode settings of the DECtalk terminal. 



FORMAT 

DTK$SET_MODE voice-id [, new-mode] [, old-mode] 

• 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

• 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 


Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

• 


new-mode 

VMS usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 


DECtalk mode to be set. The optional new-mode argument is the address 
of a longword bit mask containing the specified mode. Valid values for 
new-mode are: 



• DTK$M-SQUARE 

• DTK$M_ASCII (valid for the DTC01 device only) 

• DTK$M_MINUS 

• DTK$M-EUROPE (valid for the DTC03 device only) 

• DTK$M_SPELL (valid for the DTC03 device only) 



It is possible to perform a logical OR operation on the bits in the bit mask 
together to set more than one mode at a time. Any mode not specified is 
reset. If the new-mode argument is omitted, the current mode is unchanged. 

• 


old-mode 

VMS usage: longword—unsigned 
type: longword (unsigned) 

access: write only 


mechanism: by reference 


DTK-25 










DTK$SET_MODE 


Current mode settings of the DECtalk device. The optional old-mode 
argument is the address of a longword bit mask that receives the current 
DECtalk settings. 


DESCRIPTION DTK$SET_MODE controls the mode settings for the DECtalk device. Note 

that any modes not explicitly set are reset by DTK$SET_MODE. 

DTK$SET_MODE has two optional parameters, new-mode and old-mode. 

By specifying different combinations of these arguments, DTK$SET_MODE 
can be used in various ways. 

• To use DTK$SET_MODE to determine the current mode settings, use the 
following format: 

DTK$SET_MODE (voice_id ,,old_mode) 

• To use DTK$SET_MODE to set the bits without regard to their current 
setting, use the following format: 

DTK$SET_MODE (voice_id ,new_mode) 

• To use DTK$SET_MODE to save the current settings, set new modes, and 
later restore the original settings, use the following format: 

DTK$SET_MODE (voice_id ,new_mode ,save_old_settings) 

This retrieves the current bit settings and then sets the mode according to 
the new-mode argument. 

Later, to restore the mode to its former state, specify the following 
format: 

DTK$SET_MODE (voice-id ,save_old_settings) 

This sets the new mode setting according to those previously retrieved. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

DTK$_WRONUMARG 

DTK$_INVVOID 

DTK$_INVMODE 


Normal successful completion. 
Wrong number of arguments. 
Invalid voice-id. 

Invalid mode specified. 
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DTK$SET_SPEECH_MODE 


DTK$SET_SPEECH_MODE Turn Speech Mode 

On and Off 

The Turn Speech Mode On and Off routine either starts or stops the 
DECtalk device's speech. 


FORMAT 

DTK$SET_SPEECH_MODE 

voice-id , new-mode 
[, old-mode] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 



Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


new-mode 

VMS usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 


Mode to be set. The new-mode argument is the address of an unsigned 
longword containing the specified mode. Valid values are: 


DTK$K_SPEAK 

DTK$K_STOP 

DTK$K_HALT 


Start speaking. 

Stop speaking when current text is completed. 
Stop speaking immediately. 


If the new-mode argument is omitted, the current mode is unchanged. 


old-mode 

VMS usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
write only 
by reference 


Current speech mode of the DECtalk device. The optional old-mode 
argument is the address of an unsigned longword that receives the current 
mode setting before enabling the new mode. The values returned in old¬ 
mode are the same as those valid for the new-mode argument. 
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DTK$SET_SPEECH_MODE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


DTK$SET_SPEECH_MODE starts or stops the speech of the DECtalk device. 
When stopping DECtalk's speech, the user can either stop the DECtalk device 
immediately or stop it after it has finished speaking. Because 
DTK$SET_SPEECH—MODE is used to set a new speech mode, the new¬ 
mode argument is required. 


SS$_NORMAL 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVMODE 


Normal successful completion. 
Invalid voice-id. 

Wrong number of arguments. 
Invalid mode specified. 
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DTK$SET_TERMINAI_MODE 


DTK$SET_TERMINAL-MODE Set the Mode for 

the Video Terminal 
Connected to the 
DECtalk Device 

The Set the Mode for the Video Terminal Connected to the DECtalk Device 
routine controls the attributes of the video terminal connected to the 


DECtalk device. 

FORMAT 

DTK$SET_TERMINAI_MODE 

voice-id [, new-mode] 

[, old-mode] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 



Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


new-mode 

VMS usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

DECtalk mode to be set. The optional new-mode argument is the address 
of a longword bit mask containing the specified mode. Valid values for 
new-mode are: 

• DTK$M_HOST 

• DTK$M_SPEAK 

• DTK$M —EDITED 

• DTK$M —HARD 

• DTK$M_SETUP 

• DTK$M_FILTER 
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DTK$SET—TERMINAI_MODE 



It is possible to perform a logical OR operation on these values to set more 
than one mode at a time. Any mode not specified is reset. If the new-mode 
argument is omitted, the current mode is unchanged. 


old-mode 


VMS usage: 
type: 
access: 
mechanism: 


mask_longword 
longword (unsigned) 
write only 
by reference 


Current mode settings of the DECtalk device. The optional old-mode 
argument is the address of a longword bit mask that receives the current 
DECtalk settings. 


DESCRIPTION 


DTK$SET_TERMINAL_MODE controls the mode settings for the video 
terminal connected to the DECtalk device. Note that any modes not explicitly 
set are reset by DTK$SET_TERMINAL —MODE. 


DTK$SET_TERMINAL_MODE has two optional parameters, new-mode 
and old-mode. By specifying different combinations of these arguments, 
DTK$SET_TERMINAL_MODE can be used in various ways. 

• To use DTK$SET_TERMINAL—MODE to determine the current mode 


settings, use the following format: 

DTK$SET_TERMINAI_MODE (voice_id „old_mode) 

To use DTK$SET_TERMINAL —MODE to set the bits without regard to 
their current setting, use the following format: 


DTK$SET_TERMINAI_MODE (voice_id ,new_mode) 


• To use DTK$SET_TERMINAL—MODE to save the current settings, set 
new modes, and later restore the current settings, use the following 
format: 


DTKSSET—TERMINAI_MODE 

This retrieves the current bit 
the new-mode argument. 


(voice_id ,new_mode ,save_old_settings) 
settings and then sets the mode according to 


Later, to restore the mode to its former state, specify the following 
format: 


DTKSSET—TERMINAI_MODE (voice-id ,save_old—settings) 

This sets the new mode settings according to those previously retrieved. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 
DTK$_WRONUMARG 
DTK$_INVVOID 
DTK$_INVMODE 


Normal successful completion. 
Wrong number of arguments. 
Invalid voice-id. 


Invalid mode specified. 
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DTK$SET_VOICE 


DTK$SET_VOICE Set Voice Characteristics 



The Set Voice Characteristics routine changes the DECtalk voice 
characteristics to match those specified. 

FORMAT 

DTK$SET_VOICE voice-id [ f new-voice] [,speech-rate] 

[,comma-pause] [,period-pause] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

new-voice 

VMS usage: longword_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Type of voice. The optional new-voice argument is the address of a signed 
longword containing any valid new-voice value. Valid values for new-voice 
are: 

DTK$K_VOICE_MALE Standard male voice 

DTK$K_VOICE_FEMALE Standard female voice 

DTK$K_VOICE_CHILD Standard child voice 

DTK$K_VOICE_DEEP_MALE Deep male voice 

DTK$K_VOICE _DEEP_FEMALE Deep female voice 

DTK$K_VOICE—OLDER—MALE Older male voice 

DTK$K_VOICE—LIGHT—FEMALE Light female voice 
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DTK$SET_VOICE 


speech-rate 


VMS usage: 
type: 
access: 
mechanism: 


longword—signed 
longword (signed) 
read only 
by reference 


Rate at which DECtalk speaks, measured in words per minute. The optional 
speech-rate argument is the address of a signed longword containing this 
rate. The valid range of values for speech-rate is 120 to 350 words per 
minute. 


comma-pause 

VMS usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 


Number of milliseconds by which to increase the time DECtalk pauses after 
a comma. The optional comma-pause argument is the address of a signed 
longword containing this number. A value of zero resets the pause time to 
the hardware default value. 


period-pause 


VMS usage: 
type: 
access: 
mechanism: 


longword_unsigned 
longword (unsigned) 
read only 
by reference 


Number of milliseconds by which to increase the time DECtalk pauses after 
a period. The optional period-pause argument is the address of a signed 
longword containing this number. A value of zero resets the pause time to 
the hardware default value. 


DESCRIPTION DTK$SET_VOICE changes the DECtalk voice characteristics to match those 

specified. DTK$SET_VOICE can change the voice type, the rate of speech, 
and the number of milliseconds DECtalk pauses after commas and periods. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVARG 

OTS$_xxxx 


Normal successful completion. 
Any error from $QIO. 

Invalid voice-id. 

Wrong number of arguments. 
Invalid argument. 

Any error from OTS$CVT_l_TU. 
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DTK$SPEAK_FILE 



DTK$SPEAK_FILE Speak the Text in a Specified 

File 

The Speak the Text in a Specified File routine speaks the text contained in 
the specified file. 



FORMAT 

DTK$SPEAK_FI LE 

voice-id, filespec 




[, completion-mode] 

RETURNS 

VMS usage: 

cond_value 


type: 

longword (unsigned) 


access: 

write only 



mechanism: 

by value 



ARGUMENTS 


voice-id 

VMS usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


filespec 

VMS usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


File specification of the file containing the text to be spoken. The filespec 
argument is the address of a descriptor pointing to this file. 


completion-mode 


VMS usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Mode characteristic. The optional completion-mode argument is the address 
of an unsigned longword containing the specified mode. Valid values for the 
completion-mode argument are: 

DTK$K_IMMED Return to the user immediately (default). 

DTK$K_WAIT Wait until the text is completely spoken. 

DTK$K_STATUS Wait until the text is completely spoken, and then 

return a phone status. 
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DTK$SPEAK_FILE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


DTK$SPEAK—FILE speaks the text contained in the specified file. 


SS$_NORMAL 

SS$_xxxx 

RMS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVMODE 


Normal successful completion. 
Any error from $QIO. 

Any error generated by RMS. 
Invalid voice-id. 

Wrong number of arguments. 
Invalid mode specified. 
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DTK$SPEAK_PHONEMIC_TEXT Speak the 

Specified 
Phonemic Text 

The Speak the Specified Phonemic Text routine sends the specified 
phonemic text to the DECtalk device to be spoken. 


FORMAT 

DTK$SPEAK_PHONEMIC_TEXT 

voice-id, text 




[, completion-mode] 

RETURNS 

VMS usage: 

cond_value 


type: 

longword (unsigned) 



access: 

write only 



mechanism: 

by value 


ARGUMENTS 

voice-id 

VMS usage: 

identifier 



type: 

longword (unsigned) 



access: 

read only 



mechanism: 

by reference 



Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


text 

VMS usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Phonemic text to be spoken. The text argument is the address of a descriptor 
pointing to the specified phonemic representation of the text. 
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DTK$SPEAK_PHONEMIC_TEXT 



completion-mode 


VMS usage: 
type: 
access: 
mechanism: 


longword_unsigned 
longword (unsigned) 
read only 
by reference 


Mode characteristic. The optional completion-mode argument is the address 
of an unsigned longword containing the specified mode. Valid values for the 
completion-mode argument are: 


DTK$K_IMMED 
DTK$K_WAIT 
DTK$K_ST ATUS 


Return to the user immediately (default). 

Wait until the text is completely spoken. 

Wait until the text is completely spoken, and then 
return a phone status. 


DESCRIPTION DTK$SPEAK_PHONEMIC_TEXT sends the specified phonemic 

representation of some text to the DECtalk device. This text contains the 
phonetic representations of the words to be spoken; that is, the words are 
spelled as they are pronounced. The DECtalk device then speaks this text. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVMODE 

DTK$_ONHOOK 


Normal successful completion. 
Any error from $QIO. 

Invalid voice-id. 

Wrong number of arguments. 
Invalid mode specified. 

Phone is on the hook (inactive). 
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DTK$SPEAK_TEXT Speak the Specified Text 



The Speak the Specified Text routine sends the specified text to the 
DECtalk device to be spoken. 

FORMAT 

DTK$SPEAK_TEXT voice-id, text [, completion-mode] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

text 

VMS usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text to be spoken. The text argument is the address of a descriptor pointing 
to the specified text. 

completion-mode 

VMS usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mode characteristic. The optional completion-mode argument is the address 
of an unsigned longword containing the specified mode. Valid values for the 
completion-mode argument are: 

DTK$K_IMMED Return to the user immediately (default). 

DTK$K_WAIT Wait until the text is completely spoken. 

DTK$K_STATUS Wait until the text is completely spoken, and then 

return a phone status. 
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DTK$SPEAK_TEXT 


I 


DESCRIPTION DTK$SPEAK_TEXT sends the specified text to the DECtalk device. The 

DECtalk device then speaks this text. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVMODE 

DTK$_ONHOOK 


Normal successful completion. 
Any error from $QIO. 

Invalid voice-id. 

Wrong number of arguments. 
Invalid mode specified. 

Phone is on the hook (inactive). 
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DTK$SPELI_TEXT Spell Text 



The Spell Text routine causes DECtalk to pronounce each letter of the 
specified text. 

FORMAT 

DTK$SPELI_TEXT voice-id, text [ r completion-mode] 

RETURNS 

VMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

text 

VMS usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text to be spelled out by DECtalk. The text argument is the address of a 
descriptor pointing to the specified string. 

completion-mode 

VMS usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The optional completion mode characteristic. The completion-mode 
argument is the address of a longword bit mask containing the specified 
mode. Valid values for the completion-mode argument are: 

DTK$K_IMMED Return to the user immediately (default). 

DTK$K_WAIT Wait until the text is completely spoken. 

DTK$K_STATUS Wait until the text is completely spoken, then return a 

phone status. 
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DTK$SPELI_TEXT 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


DTK$SPELL__TEXT causes DECtalk to pronounce each letter of the specified 
text individually, rather than treat the text as a word. For example, DECtalk 
would normally pronounce USA as "oosa." Calling DTK$SPELL_TEXT 
causes DECtalk to pronounce USA as "U, S, A." 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVMODE 

DTK$_ONHOOK 


Normal successful completion. 

Any error from $QIOW. 

Invalid voice-id. 

Wrong number of arguments. 
Invalid completion-mode specified. 
Phone is on the hook (inactive). 
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DTK$TERMINATE Terminate DECtalk 



The Terminate DECtalk routine terminates the use of an initialized DECtalk 
device. 

FORMAT 

DTKSTERMINATE voice-id 

RETURNS 

VMS usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

DESCRIPTION 

DTK$TERMINATE terminates the use of the specified DECtalk device. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SSS—Xxxx Any error from $DASSGN. 

LIB$_xxxx Any error from LIB$FREE_VM or LIB$FREE_EF. 

DTK$_WRONUMARG Wrong number of arguments. 
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